Set known tags by id on TagMap and spans (otlp - tag registry - phase 2) by dougqh · Pull Request #12715 · DataDog/dd-trace-java

dougqh · 2026-10-01T18:39:00Z

What Does This Do

Adds setting a known tag by its id to TagMap and the span API, on top of the tag registry from #12354 (stacked on it; the diff here is only this PR).

TagMap.set(long tagId, value) for Object, CharSequence, and the primitives. The entry is built under the tag's canonical name from KnownTagCodec.nameOf, skipping the canonicalizing name lookup the String setters pay on every new entry. An id that names no known tag is rejected.
TagMap.Entry.create(long tagId, value), the public way to build an entry ahead of time (as decorators do for cached entries), at the same layer as AgentSpan.setTag. It has the same contract as the name-keyed create: a null or empty value yields no entry.
AgentSpan.setTag(long tagId, value), as default methods that resolve the id to its name and delegate to the String setter, so every AgentSpan implementation stays correct with no changes.
DDSpan / DDSpanContext overrides with the same behavior as the String family: TagInterceptor still runs on the tag's name (it is name-keyed), primitives still box only when the tag might be intercepted, and the http.status_code quirk is kept. The difference is that a stored tag is set by id.
TagMap hashes entries by tag id. TagMap.Entry holds a 64-bit tag hash, computed once at construction: a known tag's id, or a custom tag's name hash in the low 32 bits. An id's serial sits in bits 63-48, so the two can never collide.
- tagId() becomes a field read instead of a keyOf lookup.
- Name lookups (getEntry, getAndRemove) take one keyOf, instead of canonicalizing and then hashing the name separately.
- Buckets fold the hash from bit 48, so known tags spread by serial. A custom tag's bucket hash is unchanged.
- BucketGroup keeps its int hashes, so only Entry grows: int to long costs 8 bytes per entry because of alignment. That is an accepted temporary cost until the dense store.
First caller: BaseDecorator.onPeerConnection / setPeerPort, which run on every client span, now set peer.hostname, peer.ipv4/ipv6 and peer.port by KnownTags id.

Motivation

Under the OTLP <-> Datadog mapping, an ID identifies one tag exactly, where a name may not. #12713 is making the tag registry direction-aware, and there peer.port becomes two tags (the server's port on outbound spans, the client's on inbound ones) that share a Datadog name. Writers then need to set the specific tag, which is what an id expresses. This PR provides that API, independent of the direction work:

            ┌──► #12713  (registry: span directions)  ──┐
#12354 ─────┤                                           ├──► next: writers resolve to ids by direction
            └──► this PR (set tags by id)  ─────────────┘

It follows the API shape of #11901, but implemented on the current TagMap rather than the dense store, which #11901 is stacked on. The dense store can later swap the implementation behind the same signatures.

Additional Notes

Not in this PR: Ledger/builder support, which will arrive with a caller. Id-keyed TagMap.getEntry(long) / getAndRemove(long) are included, so clearing a tag by id removes it by id rather than round-tripping through its name.
Map contract unchanged, deliberately: Entry.hashCode() still returns the bucket hash rather than key.hashCode() ^ value.hashCode(), and TagMap still compares by identity. Both were already the case before this PR; changing them is a separate behavior change.
Shared names after Scope OpenTelemetry tag names by span direction in the tag registry (otlp - tag registry - phase 2) #12713: an entry set by a per-direction id (for example PEER_PORT_OUTBOUND_ID) hashes by that id, so on this PR alone a lookup by the shared name "peer.port" will not find it. Phase 3 (Resolve direction-dependent tag names by the span's kind (otlp - tag registry - phase 3) #12731) handles both sides: spans resolve the name by their direction, and a TagMap lookup by the shared name probes its per-direction ids.
Merge order with Scope OpenTelemetry tag names by span direction in the tag registry (otlp - tag registry - phase 2) #12713: once Scope OpenTelemetry tag names by span direction in the tag registry (otlp - tag registry - phase 2) #12713 splits peer.port, KnownTags.PEER_PORT_ID no longer exists, so BaseDecorator.setPeerPort stops compiling until it picks a direction. That is intended: it forces the direction to be chosen explicitly.
Open for reviewers — how much of the decorator change to keep:
1. All of it (as is): a real hot caller for the id API, but it couples this PR to Scope OpenTelemetry tag names by span direction in the tag registry (otlp - tag registry - phase 2) #12713 through PEER_PORT_ID.
2. Drop only setPeerPort: peer.hostname/ipv4/ipv6 keep the same ids in Scope OpenTelemetry tag names by span direction in the tag registry (otlp - tag registry - phase 2) #12713, so onPeerConnection stays a real caller with no coupling. peer.port, which server decorators also set for the client's port, moves to the direction-aware follow-up.
3. Drop the decorator change entirely: this PR becomes purely core, but has no production caller yet.
Behavior coupling with Scope OpenTelemetry tag names by span direction in the tag registry (otlp - tag registry - phase 2) #12713 (affects option 1): once Scope OpenTelemetry tag names by span direction in the tag registry (otlp - tag registry - phase 2) #12713 splits peer.port into a tag per direction, a tag stored under a per-direction id hashes by that id, but the shared name "peer.port" resolves to no id, so a lookup by name misses it. If setPeerPort switched to PEER_PORT_OUTBOUND_ID, a later getTag("peer.port") would come back empty. Until direction-aware reads land, setPeerPort therefore has to keep setting peer.port by name, which stores it as a custom tag that name lookups still find. So whichever of the two PRs merges second keeps setPeerPort name-keyed; onPeerConnection's peer.hostname/ipv4/ipv6 keep the same ids in Scope OpenTelemetry tag names by span direction in the tag registry (otlp - tag registry - phase 2) #12713 and are unaffected.
Spock tests that mock AgentSpan would see the id-keyed call directly, since a mock intercepts the default method, so every call site moved to ids would break its test's expectations. Instead, the decorator specs now mock NameKeyedAgentSpan, a test-only AgentSpan whose id-keyed overloads are final and delegate to the name-keyed ones. A mock can't override a final method, so it only sees setTag(name, value). BaseDecoratorTest.mockSpan() creates one. The specs' expectations are unchanged from master, and moving further call sites to ids needs no test change. (Spock only allows Mock() inside a spec class, so the factory lives on the base spec rather than in a trait. Other modules' 50-odd Mock(AgentSpan) sites can adopt it as they migrate.)
Tags.PEER_PORT and friends stay as they are; a @Deprecated pointing at the ids comes once callers have migrated.

Contributor Checklist

:internal-api:test (TagMap* incl. TagMapFuzzTest, 384 tests; KnownTags*; new TagMapSetByIdTest, TagMapTagHashTest, TagMapEntryCreateByIdTest), :internal-api:spotlessCheck
:dd-trace-core:test (DDSpan* incl. new DDSpanSetTagByIdTest, *taginterceptor*, *otlp*, common.writer.*, common.metrics.*; 1279 tests), :dd-trace-core:spotlessCheck. DDAgentWriterCombinedTest.unixSocketTimeoutKeepsWorkerAliveAndReconnects failed once and passed on rerun here and on the base branch; it's a timing test.

New TagMapInsertBenchmark, before vs. after hashing entries by tag id. MacBook, JDK 21, default flags, @Fork(2) triage; 12 tags per op:

Benchmark	before ns/op	after ns/op	change	B/op
`knownByName`	130.9 ± 1.8	121.1 ± 3.8	−7.5%	688 → 736
`knownById`	100.7 ± 5.5	94.7 ± 1.7	−5.9%	688 → 736
`customByName`	82.2 ± 2.7	80.6 ± 2.4	−1.9% (noise)	640 → 736

The first run caught a regression: knownById was +17%, because the id constructor resolved the name twice. That is fixed in 62f1026. Known tags net only +48 B because spreading them by serial removed a bucket collision.

:dd-java-agent:agent-bootstrap:test (*Decorator*, 413 tests), :dd-java-agent:agent-bootstrap:spotlessCheck

Jira ticket

N/A

🤖 Generated with Claude Code

datadog-official · 2026-10-01T19:01:08Z

🎯 Code Coverage (details)
• Patch Coverage: 66.28%
• Overall Coverage: 59.11% (-0.40%)

_{This comment will be updated automatically if new data arrives.

🔗 Commit SHA: de00517 | Docs | Give us feedback!}

dd-octo-sts · 2026-10-01T19:31:16Z

🟢 Java Benchmark SLOs — All performance SLOs passed

Suite	Status
Startup	🟢 pass

SLO thresholds are defined here based on automatically generated metrics. A warning is raised when results are within 5% of the threshold.

PR vs. master results

Scenario	Candidate	master	Δ (95% CI of mean)
startup:insecure-bank:iast:Agent	13.90 s	13.90 s	[-0.6%; +0.6%] (no difference)
startup:insecure-bank:tracing:Agent	12.89 s	12.96 s	[-1.3%; +0.1%] (no difference)
startup:petclinic:appsec:Agent	17.16 s	17.04 s	[-0.3%; +1.7%] (no difference)
startup:petclinic:iast:Agent	16.78 s	17.01 s	[-2.2%; -0.6%] (maybe better)
startup:petclinic:profiling:Agent	16.63 s	16.83 s	[-2.5%; -0.0%] (maybe better)
startup:petclinic:sca:Agent	17.10 s	17.01 s	[-0.4%; +1.4%] (no difference)
startup:petclinic:tracing:Agent	16.11 s	16.22 s	[-1.6%; +0.3%] (no difference)

Commit: de005172 · CI Pipeline · Benchmarking Platform UI

Load and DaCapo benchmarks can be triggered manually in the GitLab pipeline. Results will appear in the Benchmarking Platform UI after completion.

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: f38b1f88fe

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

datadog-official

The new hash fold maps _dd.djm.enabled to the reserved zero sentinel, allowing bucket collisions to lose the tag or cause lookup failures.

_{Open Bits AI session}

_{🤖 Bits Code Review · Commit f38b1f8 · @DataDog review to ask questions}

Builds on the registry directions (#12713) and id-keyed setters (#12715, included here): KnownTagCodec resolves names by direction, TagMap finds a shared name's tag whichever direction it holds, and DDSpanContext resolves direction-dependent names by the span's kind. Squashed from the review history of #12731. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Adds id-keyed setters, getters and removal to TagMap, TagMap.Entry and spans, so a writer that knows the tag skips the name lookup. Squashed from the review history of #12715. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

datadog-official

Clearing an unknown tag id with a null or empty String throws instead of following the other overloads’ no-op behavior. The alias-splitting candidate was excluded because it already exists at the supplied base commit.

_{Open Bits AI session}

_{🤖 Bits Code Review · Commit 55ab351 · @DataDog review to ask questions}

Adds id-keyed setters, getters and removal to TagMap, TagMap.Entry and spans, so a writer that knows the tag skips the name lookup. Squashed from the review history of #12715. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Builds on the registry directions (#12713) and id-keyed setters (#12715, included here): KnownTagCodec resolves names by direction, TagMap finds a shared name's tag whichever direction it holds, and DDSpanContext resolves direction-dependent names by the span's kind. Squashed from the review history of #12731. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

datadog-official

Alias-based service splitting breaks for builder and default tags: db.system becomes db.type before interception, so a split-by-tags=db.system rule no longer matches.

_{Open Bits AI session}

_{🤖 Bits Code Review · Commit b569cd2 · @DataDog review to ask questions}

Adds id-keyed setters, getters and removal to TagMap, TagMap.Entry and spans, so a writer that knows the tag skips the name lookup. Squashed from the review history of #12715. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Builds on the registry directions (#12713) and id-keyed setters (#12715, included here): KnownTagCodec resolves names by direction, TagMap finds a shared name's tag whichever direction it holds, and DDSpanContext resolves direction-dependent names by the span's kind. Squashed from the review history of #12731. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

span.setTag(0L, "") or a null value reached TagMap.getAndRemove(long), which rejects unknown ids, so clearing threw IllegalArgumentException while every id-keyed setter ignores an unknown id. removeTag(long) now ignores it too. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

The long-valued setters prechecked with needsIntercept, but when the interceptor declined the tag they discarded the box it was given and stored the primitive. Follow the same precheckIntercept -> setBox shape as the other primitive setters, so TagMap keeps the box. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

peer.port is declared per direction in the registry (#12713), so it has no direction-free id: BaseDecorator, shared by client and server decorators, sets it by name, and the set-by-id tests use an unshared int tag. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Builds on the registry directions (#12713) and id-keyed setters (#12715, included here): KnownTagCodec resolves names by direction, TagMap finds a shared name's tag whichever direction it holds, and DDSpanContext resolves direction-dependent names by the span's kind. Squashed from the review history of #12731. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

datadog-official

ID-keyed peer.port entries lose their identity in read-through TagMaps: removing one direction hides the other, and replacing an inherited entry reports no previous value.

_{Open Bits AI session}

_{🤖 Bits Code Review · Commit de00517}

datadog-official · 2026-10-13T15:11:19Z

+  public Entry getAndRemove(long tagId) {
+    this.checkWriteAccess();
+
+    return this.getAndRemove(Entry.requireKnownName(tagId), tagId);


Preserve tag identity in read-through tombstones

When a frozen parent contains both PEER_PORT_INBOUND_ID and PEER_PORT_OUTBOUND_ID, removing the inbound ID from its child also hides the outbound entry. Tombstones store the shared name "peer.port", so subsequent lookups suppress both IDs instead of only the removed one. Track tag identity consistently across tombstone creation, lookup, clearing, and inherited iteration.

React: 👍 useful · 👎 wrong · 😕 unclear · 👀 right, but not acting on it

What each reaction means

👍 Useful: correct, and you're fixing it or will.

👎 Wrong: the finding is incorrect, for example the bug can't happen or the code was misread.

😕 Unclear: you can't tell what it means or why it matters.

👀 Right, not acting: correct, but intended, out of scope for this PR, a known risk, or too minor.

_{🤖 Bits Code Review} _{· Open Bits AI session}

datadog-official · 2026-10-13T15:11:19Z

    // an OpenTelemetry rename must canonicalize the same way, or it would hash to the wrong bucket
    // and silently miss the entry stored under the Datadog name.
-    String canonicalTag = KnownTagCodec.canonicalTagName(tag);
+    long tagHash = Entry.tagHashOf(tag);


Preserve tag identity when retrieving inherited previous values

When a frozen parent stores PEER_PORT_OUTBOUND_ID, child.getAndSet(Entry.create(PEER_PORT_OUTBOUND_ID, newValue)) returns null instead of the inherited previous entry. Its parent fallback calls getEntry(newEntry.tag), which hashes the shared name "peer.port" as a custom tag and misses the ID-keyed entry. Preserve newEntry.tagHash in the parent fallback to maintain the previous-value contract. That fallback lies outside the diff hunks.

React: 👍 useful · 👎 wrong · 😕 unclear · 👀 right, but not acting on it

What each reaction means

👍 Useful: correct, and you're fixing it or will.

👎 Wrong: the finding is incorrect, for example the bug can't happen or the code was misread.

😕 Unclear: you can't tell what it means or why it matters.

👀 Right, not acting: correct, but intended, out of scope for this PR, a known risk, or too minor.

_{🤖 Bits Code Review} _{· Open Bits AI session}

dougqh added type: feature Enhancements and improvements comp: core Tracer core tag: no release notes Changes to exclude from release notes tag: ai generated Largely based on code generated by an AI or LLM labels Oct 1, 2026

dougqh mentioned this pull request Oct 1, 2026

Scope OpenTelemetry tag names by span direction in the tag registry (otlp - tag registry - phase 2) #12713

Merged

2 tasks done

dougqh commented Oct 1, 2026

View reviewed changes

Comment thread ...bootstrap/src/main/java/datadog/trace/bootstrap/instrumentation/decorator/BaseDecorator.java

dougqh marked this pull request as ready for review October 1, 2026 19:37

dougqh requested review from a team as code owners October 1, 2026 19:37

dougqh requested review from bric3 and mcculls and removed request for a team October 1, 2026 19:37

chatgpt-codex-connector Bot reviewed Oct 1, 2026

View reviewed changes

Comment thread internal-api/src/main/java/datadog/trace/api/TagMap.java Outdated

datadog-official Bot reviewed Oct 1, 2026

View reviewed changes

Comment thread internal-api/src/main/java/datadog/trace/api/TagMap.java Outdated

dougqh mentioned this pull request Oct 2, 2026

Resolve direction-dependent tag names by the span's kind (otlp - tag registry - phase 3) #12731

Draft

2 of 7 tasks

dougqh changed the title ~~Set known tags by id on TagMap and spans~~ Set known tags by id on TagMap and spans (otlp - tag registry - phase 2) Oct 2, 2026

mcculls reviewed Oct 7, 2026

View reviewed changes

Comment thread dd-trace-core/src/main/java/datadog/trace/core/DDSpanContext.java Outdated

mcculls reviewed Oct 7, 2026

View reviewed changes

Comment thread internal-api/src/main/java/datadog/trace/api/TagMap.java Outdated

mcculls approved these changes Oct 7, 2026

View reviewed changes

dougqh force-pushed the dougqh/tag-registry-otel branch from c3c341e to e49a183 Compare October 7, 2026 12:50

dougqh force-pushed the dougqh/tag-id-setters branch from c947ea5 to 55ab351 Compare October 7, 2026 12:50

dougqh force-pushed the dougqh/tag-registry-otel branch from e49a183 to 44e132c Compare October 7, 2026 13:11

dougqh requested a review from a team as a code owner October 7, 2026 13:11

dougqh removed the request for review from a team October 7, 2026 13:11

dougqh requested a review from vandonr October 7, 2026 13:11

datadog-official Bot reviewed Oct 7, 2026

View reviewed changes

Comment thread dd-trace-core/src/main/java/datadog/trace/core/DDSpan.java

vandonr approved these changes Oct 7, 2026

View reviewed changes

dougqh force-pushed the dougqh/tag-id-setters branch from 55ab351 to b569cd2 Compare October 8, 2026 12:56

Base automatically changed from dougqh/tag-registry-otel to master October 8, 2026 21:33

datadog-official Bot reviewed Oct 8, 2026

View reviewed changes

Comment thread internal-api/src/main/java/datadog/trace/api/TagMap.java

Set known tags by id on TagMap and spans

3ab5862

Adds id-keyed setters, getters and removal to TagMap, TagMap.Entry and spans, so a writer that knows the tag skips the name lookup. Squashed from the review history of #12715. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

dougqh force-pushed the dougqh/tag-id-setters branch from b569cd2 to 3ab5862 Compare October 9, 2026 12:37

dougqh and others added 3 commits October 9, 2026 10:01

dougqh mentioned this pull request Oct 9, 2026

Route intercepted tags by id instead of by name #12817

Open

Merge branch 'master' into dougqh/tag-id-setters

de00517

dougqh requested a review from a team as a code owner October 13, 2026 15:00

dougqh requested review from rachelyangdog and removed request for a team October 13, 2026 15:00

dougqh enabled auto-merge October 13, 2026 15:09

datadog-official Bot reviewed Oct 13, 2026

View reviewed changes

Navigation Menu

Repository navigation

Set known tags by id on TagMap and spans (otlp - tag registry - phase 2) - #12715

Set known tags by id on TagMap and spans (otlp - tag registry - phase 2)#12715
dougqh wants to merge 5 commits into
masterfrom
dougqh/tag-id-setters

dougqh commented Oct 1, 2026 •

edited

Loading

Uh oh!

datadog-official Bot commented Oct 1, 2026 •

edited by datadog-prod-us1-4 Bot

Loading

Uh oh!

Uh oh!

dd-octo-sts Bot commented Oct 1, 2026 •

edited

Loading

Uh oh!

chatgpt-codex-connector Bot left a comment

Uh oh!

Uh oh!

datadog-official Bot left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

datadog-official Bot left a comment

Uh oh!

Uh oh!

datadog-official Bot left a comment

Uh oh!

Uh oh!

datadog-official Bot left a comment

Uh oh!

datadog-official Bot Oct 13, 2026

Uh oh!

datadog-official Bot Oct 13, 2026

Uh oh!

This branch has not been deployed

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

dougqh commented Oct 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What Does This Do

Motivation

Additional Notes

Contributor Checklist

Jira ticket

Uh oh!

datadog-official Bot commented Oct 1, 2026 • edited by datadog-prod-us1-4 Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

dd-octo-sts Bot commented Oct 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🟢 Java Benchmark SLOs — All performance SLOs passed

Uh oh!

chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

Uh oh!

datadog-official Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

datadog-official Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

datadog-official Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

datadog-official Bot left a comment

Choose a reason for hiding this comment

Uh oh!

datadog-official Bot Oct 13, 2026

Choose a reason for hiding this comment

Uh oh!

datadog-official Bot Oct 13, 2026

Choose a reason for hiding this comment

Uh oh!

This branch has not been deployed

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

dougqh commented Oct 1, 2026 •

edited

Loading

datadog-official Bot commented Oct 1, 2026 •

edited by datadog-prod-us1-4 Bot

Loading

dd-octo-sts Bot commented Oct 1, 2026 •

edited

Loading